home *** CD-ROM | disk | FTP | other *** search
/ Just Call Me Internet / Just Call Me Internet.iso / prog / atari / m2 / cat3src / cat / doku / newproto.txt < prev   
Text File  |  1997-10-26  |  10KB  |  275 lines
  1. Neues Protokoll fr CAT:
  2.  
  3. Basisnachricht:
  4.  
  5. 0x8003
  6.  
  7. Aufbau: 
  8.  
  9. msgbuf[0] = 0x8003; (* Message-ID *)
  10. msgbuf[1] = apId;   (* CAT bzw. Kommunikationspartner, Absender halt *)
  11. msgbuf[2] = 0;      (* Oversize, immer 0 *)
  12. msgbuf[3] = sub-opcode;
  13. msgbuf[4+5] = L„nge des Buffers;
  14. msgbuf[6+7] = Adresse des Buffers;
  15.  
  16. Die Kommunikation l„uft haupts„chlich unidirectional ab, d.h. 
  17. eine Applikation fordert etwas an und CAT antwortet. Nur sehr wenige 
  18. Nachrichten werden von CAT unaufgefordert verschickt. 
  19. Prinzipiell l„uft es so:
  20. Die Applikation m”chte etwas wissen und fragt bei CAT nach. Dazu bergibt 
  21. es einen Buffer und die L„nge dieses Buffers. CAT kopiert die gewnschte
  22. Information in den Buffer. Da man teilweise auch variabel lange 
  23. Daten abfragen m”chte, gibt es folgende M”glichkeit: Das ACC fragt mit 
  24. Bufferl„nge 0 an und erh„lt als Antwort in der Bufferl„nge die notwendige
  25. L„nge des Buffers, um die gewnschte Information aufnehmen zu k”nnen. 
  26. Da die L„nge, die CAT zurckliefert, die reine L„nge der Daten ist, 
  27. sollte man noch ein Byte fr das anh„ngenden Nullzeichen als String-
  28. abschluž hinzurechnen. Bei einer L„nge von 0 ist die Information
  29. nicht verfgbar. Man kann sie trotzdem abfragen, erh„lt aber halt einen 
  30. leeren String zurck. Nach der L„ngenabfrage kann die andere Applikation 
  31. mit einem passend allozierten Buffer nochmal anfragen. 
  32. Der Buffer muž unter Systemen mit memory protection von CAT beschreibbar 
  33. sein. CAT selber stellt keinen Buffer dafr zur Verfgung. 
  34.  
  35. Sollte der bergebene Buffer fr die Daten nicht ausreichen, so gibt
  36. CAT keinerlei Daten zurck, sondern liefert eine ERROR-Antwort zurck.
  37.  
  38. Dieses Protokoll sollte auch fr andere Frontends (namentlich: THE_DOT)
  39. implementierbar sein, da auch eine Teilimplementation mit den notwendigen
  40. Funktionen z.B. fr CATalog m”glich ist. Dafr reicht es, die An- und 
  41. Abmeldung zu implementieren und die Abfragen fr Name, Betreff und Gruppe.
  42.  
  43. Alle Werte bis auf die apId sind brigens unsigned!
  44.  
  45. Folgende Sub-Opcodes sind definiert:
  46.  
  47. 00:     ACKNOWLEDGE (kein Buffer)
  48. 01:     ERROR (kein Buffer)
  49. 02:     Anmeldung bei CAT
  50. 03:     Abmeldung bei CAT
  51. 04:     Abfrage Absender
  52. 05:     Abfrage Realname
  53. 06:     Abfrage Empf„nger
  54. 07:     Abfrage MsgId (#-Zeile)
  55. 08:     Abfrage lange MsgId (I-Zeile)
  56. 09:     Abfrage '-'-Zeile
  57. 10:     Abfrage Ref-Id (R-Zeile)
  58. 11:     Abfrage Stichwort
  59. 12:     Abfrage Organization (O-Zeile)
  60. 13:     Abfrage Gateway (Y-Zeile)
  61. 14:     Abfrage Distribution (D-Zeile)
  62. 15:     Abfrage Mime (M-Zeile)
  63. 16:     Abfrage Status pers”nliche Nachricht
  64. 17:     Abfrage Followup-To (F-Zeile)
  65. 18:     Abfrage Reply-To
  66. 19:     Abfrage Message-Text
  67. 20:     Abfrage Message-Datum
  68. 21:     Abfrage Status-Datum
  69. 22:     Abfrage Gruppe
  70. 23:     Abfrage Originaltext, wie in Datenbank gespeichert
  71. 24:     Abfrage eigene Nachricht
  72. 25:     Abfrage eindeutige Id
  73. 26:     Abfrage Sender-Name aus Sender-Zeile (S-Zeile)
  74. 27:     Abfrage Name im Fenster
  75. 100:    Neue Nachricht in Fenster (CAT => ACC)
  76. 101:    CAT wird beendet
  77.  
  78. Weitere Sub-Opcodes werden bei Bedarf eingefhrt.
  79.  
  80. Einige Sub-Opcodes sind zwar definiert und werden von CAT auch bearbeitet,
  81. aber da die Daten nicht vorhanden sind, wird immer 0 als L„nge zurckgegeben 
  82. und keine Daten. Dies betrifft insbesondere Followup-To und teilweise 
  83. ReplyTo.
  84.  
  85. Im folgenden werden die Sub-opcodes etwas genauer beschrieben:
  86.  
  87. 00:     ACKNOWLEDGE 
  88.  
  89. Das ist die Antwort von CAT auf die An-/Abmeldung vom ACC, wenn diese
  90. geklappt hat. Ansonsten bekommt das ACC ERROR zurck. 
  91. msgbuf[4-7] sind 0, da kein Buffer bergeben wird.
  92.  
  93. 01:     ERROR 
  94. Das ist die Antwort von CAT auf die An-/Abmeldung vom ACC, wenn diese
  95. nicht geklappt hat. Drfte nur bei extremen Speichermangel passieren.
  96. Aužerdem wird ERROR bei jeder nicht implementierten Funktion 
  97. zurckgegeben. msgBuf[4] enth„lt den sub-opcode, der zu dem Fehler
  98. fhrte. msgbuf[5-7] sind 0.
  99.  
  100. 02:     Anmeldung bei CAT
  101. Dies schickt ein ACC an CAT zur Anmeldung. Damit wird es ber 
  102. Nachrichtenwechsel automatisch informiert und kann die Informationen
  103. dann von CAT abfragen.
  104. msgbuf[4-7] sind 0, da kein Buffer bergeben wird.
  105.  
  106. 03:     Abmeldung bei CAT
  107. Damit meldet sich ein ACC wieder bei CAT ab. Das ACC wird aus der Liste
  108. der beteiligten Empf„nger ausgetragen und erh„lt als Antwort ein ACKNOWLEDGE.
  109. msgbuf[4-7] sind 0, da kein Buffer bergeben wird.
  110.  
  111. Die folgenden Funktionen sind alles Abfrage-Funktionen, die ein Element einer
  112. Nachricht abfragen k”nnen. Bei allen Elementen ist es m”glich, das CAT
  113. nichts zurckliefert. In dem Fall wird in dem Buffer einfach ein leerer
  114. String zurckgegeben. Wenn nur die L„nge abgefragt wird durch eine 
  115. bergebene Bufferl„ngee von 0, gibt CAT auch eine 0 als L„nge zurck. Die 
  116. Antwort besteht immer aus der gleichen Nachricht wie die Anfrage.
  117.  
  118. 04:     Abfrage Absender
  119. Absender der Nachricht, falls vorhanden (Mailadresse).
  120.  
  121. 05:     Abfrage Realname
  122. Realname des Absenders, falls vorhanden.
  123.  
  124. 06:     Abfrage Empf„nger 
  125. Empf„nger der Nachricht, falls vorhanden (meistens nur bei PMs)
  126.  
  127. 07:     Abfrage MsgId (#-Zeile)
  128. Message-Id aus der #-Zeile, ist immer vorhanden
  129.  
  130. 08:     Abfrage lange MsgId (I-Zeile)
  131. Lange Message-Id, meistens vorhanden
  132.  
  133. 09:     Abfrage '-'-Zeile
  134. Verkettung nach oben
  135.  
  136. 10:     Abfrage Ref-Id (R-Zeile)
  137. Verkettung ber lange Id
  138.  
  139. 11:     Abfrage Stichwort
  140. Stichwort der Nachricht, kann auch leer sein.
  141.  
  142. 12:     Abfrage Organization (O-Zeile)
  143. O-Zeile aus Outfile
  144.  
  145. 13:     Abfrage Gateway (Y-Zeile)
  146. Y-Zeile aus Outfile
  147.  
  148. 14:     Abfrage Distribution (D-Zeile)
  149. D-Zeile aus Outfile. Inhalt: K, L, M, N: Keine, Lokal, MausNet, Net
  150.  
  151. 15:     Abfrage Mime (M-Zeile)
  152. Inhalt der M-Zeile. Eventuelle Fortsetzung im Text wird nicht zurckgegeben.
  153.  
  154. 16:     Abfrage Status pers”nliche Nachricht
  155. Nur bei PMs vorhanden, sondern wird nichts zurckgeliefert.
  156.  
  157. 17:     Abfrage Follow-Up To (F-Zeile)
  158. Wird zurckgegeben, wenn es im Outfile vorhanden war, also momentan noch
  159. gar nicht. Aužerdem kann CAT es noch nicht. Daher liefert das immer einen
  160. leeren String.
  161.  
  162. 18:     Abfrage Reply-To
  163. Wird zurckgegeben, wenn es im Outfile vorhanden war, also momentan noch
  164. gar nicht. Aužerdem kann CAT es noch nicht. Daher liefert das immer einen
  165. leeren String.
  166.  
  167. 19:     Abfrage Message-Text
  168. Liefert den gesamten Text der Nachricht zurck, wie er in der Datenbank
  169. gespeichert ist. L„nge ist theoretisch nicht begrenzt, praktisch momentan
  170. auf 64 KB. Es wird von CAT momentan der Text zurckgegeben, wie er an den
  171. Editor bergeben wurde. Eventuelle Filterungen von MIME-Opcodes sind 
  172. dort schon durchgefhrt worden und der Text wurde noch nicht umbrochen, 
  173. d.h. es k”nnen lange Zeilen vorkommen. Der Text wird im internen Format 
  174. von CAT bergeben, d.h. als Zeilenende dient ein einzelnes LF.
  175.  
  176. 20:     Abfrage Message-Datum
  177. Liefert Erstellungsdatum der Nachricht im GEMDOS-Format zurck. 
  178. Im ersten Wort im Buffer das Datum, im zweiten die Zeit. Theoretisch
  179. k”nnte man das auch komplett in den Messagebuffer packen und mžte nicht
  180. einen Speicherblock bergeben, aber zur Vereinheitlichung der Implementation
  181. wird auch hier der bergebene Speicherblock benutzt.
  182.  
  183. 21:     Abfrage Statusdatum
  184. Liefert Statusdatum der pers”nlichen Nachricht im GEMDOS-Format zurck. 
  185. Wenn es keine PM ist, wird nur 0 als Zeit und Datum zurckgeliefert.
  186. Ansonsten gilt das gleiche wie bei 20.
  187.  
  188. 22:     Abfrage Gruppe
  189. Liefert den Namen der aktuellen Gruppe.
  190.  
  191. 23:     Abfrage Originaltext
  192. Liefert den gesamten Text der Nachricht zurck, wie er in der Datenbank
  193. gespeichert ist. L„nge ist theoretisch nicht begrenzt, praktisch momentan
  194. auf 64 KB. Es wird von CAT der Text zurckgegeben, wie er in der Datenbank
  195. gespeichert wurde, d.h. es wurden keine Filterungen durchgefhrt, keine
  196. Infozeilen in den Text eingeblendet etc. Der Text wird im internen Format 
  197. von CAT bergeben, d.h. als Zeilenende dient ein einzelnes LF.
  198.  
  199. 24: Abfrage eigene Nachricht 
  200. Fragt nach, ob im Fenster eine eigene Nachricht dargestellt wird.
  201. Liefert nur in der pers”nlichen Gruppe bei eigenen Nachrichten 
  202. TRUE zurck. Im Buffer wird ein Wort bergeben, das 1 ist fr eine
  203. eigene pers”nliche Nachricht, und sonst 0. Weitere Werte werden nicht 
  204. zurckgeliefert.
  205.  
  206. 25: Abfrage eindeutige Id
  207. Fragt nach einer eindeutigen ID pro Nachricht. Gibt einen unsigned long
  208. zurck, der die Nachricht innerhalb eines CAT-Laufes innerhalb einer
  209. Datenbank eindeutig identifiziert.
  210.  
  211. 26: Abfrage Absender aus Sender-Zeile
  212. Liefert den Absender zurck, wie er in der Sender-Zeile (S-Zeile) im
  213. Outfile kam
  214.  
  215. 27: Abfrage Absendername im Fenster
  216. Liefert den Namen zurck, den CAT im Fenster anzeigt. Bei eigenen
  217. pers”nlichen Nachrichten ist das der des Empf„ngers, sonst der 
  218. des Absenders.
  219.  
  220. Die folgende Nachricht wird nur von CAT an die angemeldeten Applikationen 
  221. verschickt, und zwar jedesmal, wenn im obersten Anzeigefenster eine neue 
  222. Nachricht dargestellt wird. Die Nachricht wird auch verschickt, wenn ein 
  223. Anzeigefenster nur getoppt wird.
  224.  
  225. 100: Neue Nachricht in Fenster
  226. msgbuf[4-7] sind 0, da kein Buffer bergeben wird. 
  227.  
  228. Die folgende Nachricht wird nur von CAT an die angemeldeten Applikationen 
  229. verschickt, und zwar jedesmal, wenn CAT beendet wird.
  230.  
  231. 101: CAT wird beendet
  232. Wird verschickt, wenn CAT beendet wird. msgbuf[4-7] sind 0.
  233.  
  234. Hier noch die Definition der einzelnen Nachrichten, wie sie in CAT 
  235. implementiert ist:
  236.  
  237. CONST
  238.   CatProtoMsg   = 8003H;        (* Neues CAT-Protokoll *)
  239.  
  240.   (* Sub-Opcodes fr neues CAT-Protokoll *)
  241.   (* Doku: Siehe NEWPROTO.TXT            *)
  242.   
  243.   CAT_ACK           = 0;
  244.   CAT_ERROR         = 1;
  245.   CAT_LOGIN         = 2;
  246.   CAT_LOGOFF        = 3;
  247.   CAT_SENDER        = 4;
  248.   CAT_RNAME         = 5;
  249.   CAT_RECEIVER      = 6;
  250.   CAT_MAUS_ID       = 7;
  251.   CAT_MSG_ID        = 8;
  252.   CAT_MAUS_REF      = 9;
  253.   CAT_REF           = 10;
  254.   CAT_TOPIC         = 11;
  255.   CAT_BOX           = 12;
  256.   CAT_GATE          = 13;
  257.   CAT_DIST          = 14;
  258.   CAT_MIME          = 15;
  259.   CAT_STATUS        = 16;
  260.   CAT_FOLLOWUP      = 17;
  261.   CAT_REPLYTO       = 18;
  262.   CAT_TEXT          = 19;
  263.   CAT_MSG_DATE      = 20;
  264.   CAT_STATUS_DATE   = 21;
  265.   CAT_GROUP         = 22;
  266.   CAT_ORG_TEXT      = 23;
  267.   CAT_IS_OWN        = 24;
  268.   CAT_UNIQUE_ID     = 25;
  269.   CAT_REAL_SENDER   = 26;
  270.   CAT_WDW_NAME      = 27;
  271.   
  272.   CAT_NEW_MSG       = 100;
  273.   CAT_TERMINATE     = 101;
  274.  
  275.